Read an accepted update's outcome later by update id (#212) - #309

Part of durable-workflow/.github#212 (the sdk-python slice). Builds on the native read route from server#1131 (native 3.6.0), and follows the PHP reference in sdk-php 3.15.0.

What changed

• Client.update_outcome(workflow_id, update_id, *, wait_for="completed", wait_timeout_seconds=None, result_type=None) reads an accepted update by id with GET /api/workflows/{workflow_id}/updates/{update_id} and returns the decoded result, including None.
  • A pending update (202 update_status: "accepted", with or without wait_timed_out) raises the new UpdateStillPending. It carries workflow_id, run_id, update_name, update_id, request_id, update_status, wait_timed_out and body, and its message says to call update_outcome() again with the update id. A pending update is never returned as None.
  • A failed update (422) raises UpdateFailed. A rejected update keeps its original rejection status and raises UpdateRejected, as submitting it does. A 404 update_not_found raises the new UpdateNotFound, a subclass of UpdateFailed, so it is not mistaken for WorkflowNotFound.
• Client.update_outcome_receipt(..., wait_for="accepted", ...) returns the raw receipt.
• Capability gate. Both methods first check capabilities.update_outcome_reads === true in cluster info. If it is missing or false, they raise RuntimeCapabilityUnsupported naming that path. Only the discovery request is made: nothing is read and nothing is resubmitted. Both methods also check that wait_for is accepted or completed and that the update id is not empty, before sending any request.
• Request details. Path segments are percent-encoded, and wait_for=completed and wait_timeout_seconds go in the query string. The route /workflows/{workflow_id}/updates/{update_id} is added to the bounded metrics route registry.
• Other entry points. WorkflowHandle.update_outcome() / update_outcome_receipt() and the sync Client / SyncWorkflowHandle wrappers are added.
• update_workflow. Its return type is unchanged; it still returns the receipt. Its docstring (and WorkflowHandle.update's) now says it returns the receipt and not the decoded result, that the Server answers at accepted when wait_for is omitted, how to tell pending from a completed None, and that update_outcome() reads the result later. No existing code path decoded update results, so no pending-to-None collapse needed fixing.
• CHANGELOG (Unreleased) and docs/sdk-reference.md are updated.

Tests

tests/test_update_outcome.py uses httpx.MockTransport and covers:

• completed with a value and with None
• result_type decoding
• a pending read after a timed-out wait, a plain pending read, and a re-read that returns the result
• an accepted and a completed receipt
• a failed update (422), update_not_found (404), and rejected updates (409/404/422)
• older Servers: capability missing, false, or no capabilities block, for both methods. Only discovery runs.
• wait_for and update-id validation, with no requests sent
• GET method, path and query string
• the metrics route
• handle and sync wrappers

Locally in Docker on Python 3.12: ruff, mypy, the Avro benchmark gate, the full unit suite (5945 passed), the regression-corpus policy, and the package build/metadata/smoke checks all pass.

🤖 Generated with Claude Code